Skip to content

feat: add context change listeners for flag subscriptions #1281

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
jonathannorris wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

feat: add context change listeners for flag subscriptions #1281

jonathannorris wants to merge 4 commits into from

Conversation

@jonathannorris
Copy link
Member

@jonathannorris jonathannorris commented Nov 5, 2025

Add Context Change Listeners for Flag Subscriptions - Proposal

Overview

Implements context change listeners for the web SDK, addressing open-feature/spec#346. Provides a type-safe way to subscribe to flag value updates when evaluation context changes.

Problem

The current Events API requires significant boilerplate to track individual flag values. This PR adds a convenient API allowing developers to subscribe directly to flag changes with minimal code.

Solution

Two approaches for subscribing to context changes are implemented as examples for discussion:

1. EvaluationDetails Subscriptions

Enhanced EvaluationDetails objects returned from evaluation methods include an onContextChanged method. The callback is invoked whenever the context changes.

const unsubscribe = client.getBooleanDetails('feature-enabled', false)
                          .onContextChanged((newDetails, oldDetails) => {
  // Called on each context change
  console.log(`Flag updated: ${newDetails.value}`);
});

2. Client-Level Subscriptions

Type-specific methods directly on the client for subscribing to context changes. Performs an initial flag evaluation and invokes the callback immediately, then again whenever the context changes.

const client = OpenFeature.getClient();
const unsubscribe = client.onBooleanContextChanged(
  'feature-enabled',
  false,
  (newDetails, oldDetails) => {
    // Called immediately with initial value, then on each context change
    updateUI(newDetails.value);
  }
);

Implementation

  • EvaluationDetailsWithSubscription - Wraps EvaluationDetails with subscription capability
  • ContextChangeSubscriptions interface - Groups subscription methods
  • evaluateWithSubscription helper - DRY wrapper for evaluation results
  • Closure-based cleanup - Consistent with existing SDK patterns

Important: Providers do NOT need to implement ContextChanged events. The SDK automatically emits these events after context changes via setContext(), making this implementation reliable and provider-agnostic.

Handler Management: Uses closure-based approach consistent with existing SDK patterns. A WeakMap-based subscription registry was considered for subscription introspection/bulk operations but would diverge from current patterns and add complexity.

Usage Example

import { useEffect, useState } from 'react';
import { OpenFeature } from '@openfeature/web-sdk';

function FeatureComponent() {
  const [featureEnabled, setFeatureEnabled] = useState(false);
  const client = OpenFeature.getClient();

  useEffect(() => {
    const details = client.getBooleanDetails('new-feature', false);
    setFeatureEnabled(details.value); // Set initial value

    // Callback is invoked on context changes
    const unsubscribe = details.onContextChanged((newDetails) => {
      setFeatureEnabled(newDetails.value);
    });

    return unsubscribe;
  }, []);

  return <div>{featureEnabled ? 'Feature Active' : 'Feature Disabled'}</div>;
}

Related Issues

Addresses open-feature/spec#346

@jonathannorris jonathannorris mentioned this pull request Nov 5, 2025
Open
@bencehornak
Copy link

bencehornak commented Nov 6, 2025

Thanks for the PoC, @jonathannorris! The first thing coming to my mind regarding the proposal is that it is reacting to variable value changes caused by context changes, but not to the ones caused by the provider backend (i.e. when an admin flips a flag or when a scheduled feature activation is due). This second one is a much more fundamental change, because providers also need to implement some server-to-client communication or polling to their own backends, but this is the way to support on-the-fly variable updates.

You and your colleagues implemented this in the DevCycle Android SDK with SSE, that's inspired me to open the referenced ticket in the spec repo:

https://github.com/DevCycleHQ/android-client-sdk/blob/b6794ab8a88f6ee447b8caf3c2ce92f10099d7f5/android-client-sdk/src/main/java/com/devcycle/sdk/android/api/DevCycleClient.kt#L145-L170

https://github.com/DevCycleHQ/android-client-sdk/blob/b6794ab8a88f6ee447b8caf3c2ce92f10099d7f5/android-client-sdk/src/main/java/com/devcycle/sdk/android/model/Variable.kt#L94-L112

So regarding the proposed API: as the author of the FeatureComponent based on your example I'd expect to be able to subscribe to variable changes no matter if they were caused by context changes or the provider. What do you think about making the subscribe methods more generic by removing the word 'context' from them (e.g. details.onChanged() or client.onBooleanChanged() and expanding the scope of the PoC to handle both cases?

@lukas-reining
Copy link
Member

lukas-reining commented Nov 8, 2025 •
edited
Loading

Hey @jonathannorris, as discusses in the community meeting and described by @bencehornak, I think we would not only want to react to context changes but also to configuration changed.
In the static context SDKs, when the context is changed, the SDK calls the providers onContextChange method and the provider then typically fetches the flags. Once this is done, a configuration changed event will be emitted. [1]
This does not include the events where the provider is informed about a change by the backend which would be configuration changed.

What do you think about making the subscribe methods more generic by removing the word 'context' from them (e.g. details.onChanged() or client.onBooleanChanged() and expanding the scope of the PoC to handle both cases?

This makes sense to me @bencehornak. But we also have examples where we only want to react to one type of event.
E.g. we have the example in Angular [2] and React [3].
I think we should have this here too. It seems like the easiest way of implementing this would be to add optional parameters to the details.onChanged() or client.onBooleanChanged() methods.

This second one is a much more fundamental change, because providers also need to implement some server-to-client communication or polling to their own backends, but this is the way to support on-the-fly variable updates.

@bencehornak I do not see this as a problem, this is the case today too. If providers have a way to emit config changes they get emitted, otherwise the event will simply never trigger.
This happens in the React and Angular cases already today.

@jonathannorris jonathannorris force-pushed the feat-context-change-listeners branch from 2a84c0f to ed511e3 Compare January 2, 2026 20:44
@jonathannorris
feat: add context change listeners for flag subscriptions
4c4772c 
Signed-off-by: Jonathan Norris <jonathan@taplytics.com>
@jonathannorris
feat: update context change listeners to fire immediately for client-…
4d4e403 
…level subscriptions

Signed-off-by: Jonathan Norris <jonathan@taplytics.com>
@jonathannorris
feat: support ConfigurationChanged events and rename to generic flag …
c2de1b7 
…change subscriptions

- Rename context-specific methods to generic names (onContextChanged -> onChanged, etc.)
- Add FlagChangeSubscriptionOptions with updateOnContextChanged and updateOnConfigurationChanged
- Support both ContextChanged and ConfigurationChanged events by default
- Update tests to properly await async setContext and fix spread operator issues with class instances
- Fix hooks test to compare evaluation details by property values instead of object reference

Signed-off-by: Jonathan Norris <jonathan@taplytics.com>
@jonathannorris jonathannorris force-pushed the feat-context-change-listeners branch from 0672864 to c2de1b7 Compare January 2, 2026 21:10
@jonathannorris
chore: revert package-lock.json to match main
d5937ea 
Signed-off-by: Jonathan Norris <jonathan@taplytics.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@jonathannorris @bencehornak @lukas-reining